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1. Introduction 

Thank you for purchasing NitrOS-9. 



Please see the 'read. me' file on the distribution disk for any 
updates or changes to the information included in this manual. 

NitrOS-9 is a set of replacement nodules for Microware's OS-9 
Level II Operating System when used with the Hitachi HD6309 
microprocessor. These modules have been written to maintain near-100% 
compatibility with OS-9, with the added bonus of extra speed and 
additional features. 

This is done by using undocumented features in the Hitachi CMOS 
6309 microprocessor. The 6309 is 100% compatible with the Motorola 
6809 when running in 6809 mode. However a second mode on the 6309, 
called Native Mode, uses additional registers and instructions on the 
chip for greatly improved performance: 



Benchmark 


Stock System 
(6809) 


NitrOS-9 vl.21 
(6309) 


List 40k text file 
Text Screen 
Graphics Screen 


45 seconds 
135 seconds? 


21 seconds 
45 seconds? 


Format 360K Floppy 






Megaread 






Graphics Demo 





Almost all applications will work without modification under 
NitrOS-9. Those few that don't, such as Home Publisher, have patches 
freely available. If you encounter a module that won't run under 
NitrOS-9, please contact your distributor at the address listed in 
Section 5. 
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NitrOS-9 is intended for use on the Tandy Color Computer 3 and 
Frank Hogg Laboratories TomCat TC9 computers which have a Hitachi 
HD6309 CPU installed. Contact the authors (Section 5.7) for 
information on use with other 6809 systems that run GS-9 Level II. 

1.1 The Hitachi 6309 

Hitachi licensed the rights to reproduce Motorola's M6809 CPU. 
Two versions of the chip were produced by Hitachi — the HD6809, and 
the HD6309. The HD6809 is an exact duplicate of the Motorola chip. 

The 6309 was produced using a CMOS technique called microcoding, 
rather than the bit-decoded technique use to create the 6809. As a 
result, there was room available on the chip for additional registers 
and instructions. These were added by Hitachi's engineers, but due to 
the licensing arrangement, the documentation for these features was 
never released to the public by Hitachi. 

These instructions were eventually printed in the Japanese 
publication Oh!FM, and first came to the attention of North America 
on March 5 1992, when Hirotsugu Kakugawa posted them on Internet. 

Not long after that information was released, Burke & Burke 

released the first edition of its PowerBoost package. Using a 

technique called "stack massaging" (discussed later), PowerBoost 

patched sections of OS-9 to use 6309 instructions in Native Mode. 

This resulted in a noticeable increase in speed. 

1.2 Development of NitrOS-9 

Inspired by the performance of the PowerBoost package, the 
authors of NitrOS-9 began to wonder what would be involved in getting 
OS-9 to run on the 6309 completely in native mode, so that the 
advantages offered by the 6309 could be fully utilized. 

When a interrupt (IRQ) occurs on a 6809 CPU, copies of all the 
registers are pushed onto the hardware stack like this: 



CC A B DP X Y U PC 
New Stack Pointer 



Rest of Stack] 

Stack Pointer before IRQ 
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To access data pushed onto the hardware stack, OS-9 will use an 
offset from the new stack pointer to access either the register 
values just pushed onto the stack, or the values that were on the 
stack before the IRQ occurred. 

With the 6309 running in Native Mode, two additional registers 
(E and F) are also pushed onto the stack when an interrupt occurs: 



— New Registers 

CC A B E F DP X Y U PC [Rest of Stack] 

I 
-New Stack Pointer L Incorrect Pointer 



If unmodified OS-9 system modules try to access the stack, they 
will quickly run into difficulty using the original offsets from the 
new stack pointer. Since there are now two unexpected 8-bit registers 
on the stack, any pointers to DP, X, Y, U, or PC will be off by 16 
bits, or two bytes. For example, unmodified code would calculate the 
pointer to PC as pointing at U, rather than the correct position. 
This will cause strange results on any computer! 

Two techniques can be used to overcome this problem: 

- Stack Massaging; and 

- Modifying all the register stack offsets 

Stack Massaging involves rearranging the order of the 
information on the stack and resetting the stack pointer so that the 
stack appears in the order expected with a 6809. This has to happen 
each time an interrupt occurs, and has to be undone before returning 
from the interrupt. 

The second technique is straightforward, but also somewhat more 
involved. To modify all the register stack offsets, each module must 
be disassembled, and the stack offset adjusted for each system call 
supported by the module. 

Armed with this information, the authors set about the task of 
disassembling, documenting, and modifying OS-9. In the process, in 
addition to modifying all the stack offsets, the authors discovered a 
great deal about OS-9. 
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These discoveries included previously unnoticed bugs in OS-9 
(mostly small ones), sections of code that would benefit greatly from 
being rewritten for the 6309, the need for some new system calls, and 
undocumented features in current system calls. 

The result so far has been several megabytes of source code, 
extensive modifications to roost of the original OS-9 modules, and 
several improved replacement modules that were created from scratch. 
In addition, a majority of the most popular patches to OS-9 have teen 
incorporated in NitrOS-9. 

The authors are still actively developing NitrOS-9. 
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Using NitrOS-9 with your Tandy Color Computer 3 or Frank Hogg 
Laboratories Tomcat TC9 computer requires the installation of a 
Hitachi HD6309 CPU. If you aren't comfortable working inside your 
computer with a soldering iron, section 2.4 lists some vendors that 
will do the installation for you. 

Ensure that the HD6309 used is appropriate for your machine. For 
a 2MHz Tandy Color Computer 3 or FHL TC9, a HD63B09E or HD63C09E 
model chip should be used. 

As always when working with electrical equipment, ensure it is 
unplugged, and read the instructions completely before you begin the 
installation. 



2.1 Replacing the MC6809 

The quickest method of replacing the 6809 with a 6309 is to cut 
out the existing 6809, desolder the leftover pins from the 
motherboard, install a socket, and put the 6309 in the socket. 

2.2 Piggyback Installation 

ft slightly simpler method of installing the 6309 is to install 
it on top of the existing 6809, and disable the 6309: 

1. Take a 40 pin IC socket and cut off pins 5, 6, 33, 36, 
and 38. Bend pin 39 inwards. 

2. Solder a length of 30 gauge wire across the bottom of 
the socket between pin 39 and pin 1. 

3. Cut pin 39 of the 6809 cpu on the motherboard (IC1). 

4. Solder a piece of 30 gauge wire between pin 7 (+5vdc) and 
pin 39 of the 6809 to shut it off (See Section 2.3) 

5. Place the socket on top of the 6809 (IC1). Make sure 
the socket pins make firm contact with the 
corresponding 6809 pins. 
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6. Join each pair of corresponding pins with solder. 
(Except 5, 6, 33, 36, 38 and 39.) 

7. Plug in the 6309. 

2.3 Switchable Installation 

By adding a DPDT switch, it is possible to switch between the 
6809 and the 6309. Naturally, NitrOS-9 won't work with the 6809 
enabled, but a switchable installation can be useful to check the 
operation of software with a 6809. 

1. Take a 40 pin IC socket and cut off pins 5, 6, 33, 36, 
and 38. Bend pin 39 outwards, so that it can later be 
connected to the switch. 

2. Cut pin 39 of the 6809 cpu on the motherboard (IC1). 
Bend the pin upwards, and solder a piece of wire to 
it. Connect the wire now, as the pin is easier to 
access at this point. 

3. Place the socket on top of the 6809 (IC1). Make sure 
the socket pins make firm contact with the 
corresponding 6809 pins. 

4. Join each pair of corresponding pins with solder. 
(Except 5, 6, 33, 36, 38 and 39.) 

5. Connect Pins 1 and 6 of a Double-Pole, Double-Throw (DPDT) 
switch to pin 39 of the 6809 on the motherboard as shown 
in the diagram below. 

6. Connect Pins 2 and 5 of the switch to pin 39 of the socket. 

7. Connect Pin 3 of the switch to +5 volts (6809 Pin 7), and 
Pin 4 of the switch to Ground (6809 Pin 1). 
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6309 
Active 



1 3 


— +5v 
1— 6309 39 




L^ 




6809 
Active 

L— 6809 39 
— Gnd 


DPDT 

Switch 

Wiring 


T " 
I 4 t 



8. Finally, plug in the 6309. 

2.4 Third-Party Installation 

Most electronic repair stores will do the installation for a 
minimal fee, if you provide the CPU and socket. This is the simplest 
and fastest method of getting your 6309 installed by a third-party. 
The Tandy/Radio Shack repair centers in Canada will also do this 
installation for you, at their regular repair rate. 

In the United States, CoNect will install a Hitachi 63B09E CPU 
and a socket into your CoCo. The machine MUST be in working 
condition! The 68B09E will be returned unharmed. This service 
includes a 90 day limited warranty, chip and installation. Contact 
CoNect, listed in Appendix B. 

The same service is available from Northern Xposure (Appendix 
B). The 68B09E will not be returned. Due to Customs charges, this 
service is only offered within Canada. 

In Australia, contact RemComs for more information. 
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3. Software Installation 

We highly recommend that you produce a NitrOS-9 Boot floppy 
before you attempt to install NitrOS-9 on your hard drive system! 

Get your current bootlist (ident -s /dd/os9boot). 

Collect NitrOS-9 versions of all the needed system modules, and 
use your current descriptors. 

Modify any programs that need patching, as detailed in Appendix 
C Third-Party Software Compatibility. Keep these separate from your 
regular (6809) versions. 

Create a bootfile on the disk, using QS9Gen. If you are creating 
this disk using a stock OS-9 boot disk, this will give you a disk 
with a stock kernel track, and NitrGS-9's OS9Boot. 

To install the NitrOS-9 Kernel track in memory, use the CHBOOT 
command. It will replace rel, boot, and os9pl, and reboot the 
machine. Then use COBBLER to create a new boot disk with the NitrOS-9 
kernel track and OS9Boot file. 

Use Tuneport to patch /p, if necessary. 

See the Fine-Tuning information in Section 4.2 for suggestions 
about fine-tuning your system. 
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4. Technical Information 

Information on the Hitachi 6309 is contained in Appendix A. 

Additional Technical Information is contained in other 
appendices. 

Information on specific modules is contained in the Release 
History, Appendix F. Modules that have been rewritten to work with 
NitrOS-9 generally fall into three categories: 

o Modules that have simply been recompiled to handle the 
new stack offsets. 

o Modules that have been optimized to work with the 6309. 
These modules are based on the original Microware 
modules, but have been partially rewritten to take 
advantage of the 6309 instructions. 

o Modules that have been completely rewritten. These 
modules have been completely rewritten to take advantage 
of the 6309 instructions, and often their function has 
been extensively modified to improve the performance of 
NitrOS-9. 

4.1 OS-9 Compatibility 

How compatible is NitrOS-9 with Microware's OS-9? 

As far as possible, complete compatibility has been maintained 
with OS-9 Level II. Generally speaking, anything that will run 
on a stock OS-9 system will run on a NitrOS-9 system. 

The exceptions to this rule fall into three categories that 
are detailed below, along with solutions: 

1. Programs that use software timing loops. 

Tuneport is used to adjust the speed of the 'bitbanger' serial 
port on the Color Computer. Other programs such as UltiMusE 3 
can be patched to allow for the increased speed of NitrOS-9. 
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2. Programs that use instructions that are illegal on the 
6809, but are legal on the 6309. On the 6809, these illegal 
instructions are treated as NOPs, and are used on very rare 
occasions in timing loops. This is an example of one of the 
few incornpatabilities between the 6809 and the 6309. 

Patches are available for some programs, and most others have 
already been rewritten to work with the 6309. These programs 
are very rare, and have generally already been modified to 
work with the 6309. 

3. Third-party modules that have not yet been converted 
to use NitrOS-9. 

Conversion of programs so that they are compatible with 
NitrOS-9 is usually a simple and straight forward process. 
Send a copy of the module to Northern Xposure at the address 
in Section 5.7, and it will be converted. Those that wish to 
tackle the conversion themselves should see Section 4.3. 

4.2 Fine-Tuning 

This section describes some additional steps that you can take 
to obtain optirmsn performance from your system. 

Hard Drive Interleave should be reduced for optimum performance. 
The exact value to use will depend on your system. 

If you are having problems with disk fragmentation, change your 
SSS settings on your disk device (hard or floppy disk) to a higher 
nunber. This means it will allocate bigger contiguous chunks when you 
create or append to a file, particularly if you are multi-tasking 
with several programs creating/extending files at once. 

Floppy Drive Interleave can be reduced from 3 to 2. You may wish 
to leave this alone however, if you will be using the floppies with 
another system. 

Parking joysticks in the upper left corner will greatly speed up 
your system if you have a program trying to read the joysticks and/or 
mouse in the current active window. 
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Get /Put buffers are much faster on wide (horizontal images) than 
on narrow but tall ones. 

Write & Read are a fair bit faster than WritLn & ReadLn, if you 
can substitute. Even in BJSIC09, PUT is much faster than PRINT, even 
to the screen. 

When writing programs, the nmber of system calls should be 
minimized. When optimizing some programs, the authors of NitrOS-9 
discovered routines which performed a system call (I$Write) for every 
character the program displayed, ftfter adding a few lines of code to 
internally buffer the characters before outputing them, the program 
doubled in speed. 

4.3 Writing NitrOS-9 Compatible Modules 

The best reference for writing OS-9 user mode programs is the 
technical reference that comes included in the OS-9 manual. In 
addition, a good 6309 assembler reference, or a C language reference 
such as K&R will make writing programs much easier. 

If you wish to modify an existing QS-9 kernel module to work 
with NitrOS-9, familiarity with 6809 assembly language is a must. 
The module may be disassembled, and labels added where necessary in 
order to verify that the disassembly in fact re-assembles identical 
to the original module. Care must be taken to add all system 
definitions (PD.OPT, V$DESC, etc) where required. Failure to do so 
may result in unusual crashes, as NitrOS-9 contains some changes to 
these definitions. If an OS-9 defs file is used in place of a 
NitrOS-9 defs file, compatiblity cannot be guaranteed. 

Most modules, however, do not require extensive changes. Once a 
correct disassembly is produced, the module may simply be 
re-assembled with a NitrOS-9 'os9defs' file to produce the correct 
register stack offsets. The module may then be added to the system 
with the knowledge that it will work. Further optimizations may be 
performed as desired. 

This method of converting OS-9 to NitrOS-9 modules is strongly 
recommended, as it is the one used by the authors of NitrOS-9. 
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Authors creating new applications will probably wish to use the 
stock OS-9 assembler. This will allow your applications to be used on 
stock system. There are some things that should be considered though, 
in order to maintain compatability with NitrOS-9. 

When writing new OS-9 programs, it is possible to write them in 
such a way as to assure compatibility with NitrOS-9. The two 
conditions are that time-critical loops must depend on hardware and 
signals rather than software loops, and the register stack for 
interrupts should not be accessed. Simplistically, stay away from 
software timing loops and the F$SSWI system call. 

Software timing loops may be used, however, if care is taken to 
verify that the system is running NitrOS-9. ft copy of D. Native may 
be obtained from the system by using F$CpyMem, and a non-zero value 
indicates NitrOS-9 is running. This value may be checked before 
entering software timing loops, and a 6809 or 6309 loop counter can 
be chosen as appropriate. 

The F$SSWI system call should be avoided if at all possible. 
There are generally other, simpler, methods of performing internal 
subroutine calls. 
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Mustang Professional Software 
5. Credits and Other Information 
5.1 Credits 



NitrOS-9 vl.16 and earlier were primarily written by Curtis 
Boyle and Bill Nobel of Mustang Professional Software, with 
additional programming and production of the distribution package by 
Wes Gale of Gale Force Enterprises. 

NitrOS-9 vl.20 and higher were written by Curtis Boyle of 
Mustang Professional Software, and Alan DeKok of Intelligent 
Algorithms. 

This manual was written by Colin McKay. 

Thanks also go to the following individuals: 

Wes Gale of Gale Force Enterprises for his contributions to 
earlier versions of NitrOS9. 

Bruce Isted: Cart IRQ toggle patches; improved interrupt 
handling, both in CC3IO and CLOCK, F$PrsNam system call. 

Kevin Darling: Improvements in GRFDRV which speed up the 
get/put buffers. Improved memory sensing in OS9pl. Improved 
SCF line editing. Patches for GrfDrv and VDGInt for use on 
systems with more than 512k of ram. 

Ken Scales: Keytable patches for using CC3IO with DynaStar. 

Doug Fraser: FRMEM utility, MMAP patch for use with up to 
2MB of ram, RAM drive patches for use with 2MB upgrades. 

Boisy Pitre: SCF non-sharable device patches. 

Dave Wiens of Sardis Technologies: DMC no-halt floppy disk 
controller driver source. 

Any other contributors who aren't mentioned here, but are 
mentioned in the release notes. 
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Ml the Beta testers: For all their generous quantities of 
patience and skill in testing NitrOS-9. 

5.2 Copyright Notices 

NitrOS-9 and the NitrOS-9 Reference Manual are Copyright 
(C) 1994 by Mustang Professional Software 

NitrOS-9 is a trademark of Mustang Professional Software 
OS-9 is a trademark of Microware Systems Corporation 
Color Computer 3 and CoCo are trademarks of Tandy Corporation 
Tomcat and TC9 are trademarks of Frank Hogg Laboratories 
PowerBoost is a trademark of Burke & Burke 



NitrOS-9 is distributed by: 

World: Northern Xposure 
7 Greenboro Cres 
Ottawa, ON 
Canada 
KIT 1W6 



Australia: REMCOMS 

100 Whitsunday Dr 
KIRWAN. Qld. 
4817 
Australia 



5.3 Warranty 



(613)736-0329 



+61 77 734884 



The distributor warrants the product against defects in material 
or workmanship for a period of ninety days from the date of purchase 
by the original owner. This warranty is limited to repair or 
replacement of product which proves defective during this period. 

This warranty specifically excludes software defects and defects 
caused by negligence, abuse, accident, and tampering. 

If your disk becomes defective during this warranty period, mail 
it to the distributor (Section 5.7.2), postage paid. A new disk will 
be returned to you at the expense of the distributor. Disks that 
become defective outside this warranty period will be replaced for a 
$5.00 handling charge. 
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This entire manual, any accompanying computer programs, and any 
accompanying storage media, constitute a product of Mustang 
Professional Software. The product is supplied for the personal use 
of the purchaser. One copy of this product must be purchased for 
every machine on which it is installed. 

License is granted for the accompanying program to be copied 
onto the machine on which it is to be used, disks used on that 
machine, and to be backed up for archival purposes. 

5.5 Disclaimer 

Every effort has been made to ensure the accuracy of this manual 
and the quality of the product it describes. Mustang Professional 
Software makes no warranties, whether expressed, statutory, or 
implied, of any kind whatsoever as to the merchantability of the 
product or its fitness for a particular use, except as set forth 
above as the Warranty. Neither Mustang Professional Software nor the 
distributors are responsible for any loss or damage resulting from 
the use or misuse of NitrOS-9. 

5.6 Upgrades 

Upgrades to future releases of NitrOS-9 vl.xx, if and when they 
become available, will be offered for a handling charge. Upgrades 
will include an updated manual or manual pages, if appropriate. 
Registered users of NitrOS-9 will be notified by mail when upgrades 
become available. 

NitrOS-9 v2.xx, if and when it becomes available, will be 
offered at a reduced cost to registered vl.xx owners. You will be 
notified by mail when v2.xx becomes available. 

5.7 Support 

NitrOS-9 has been designed to work with as wide a variety of 
hardware and software as possible, however some problems are 
inevitable in a project of this scope. 
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If you find a bug in NitrOS-9, software that is incompatible, or 
drivers that need "souped-up", please contact your distributor or any 
of the individuals listed in the next section for assistance. 

5.7.1 Technical Assistance 

Curtis Boyle: Mail: c/o Northern Xposure 

Ulan DeKok: Mail: c/o Northern Xposure 

Internet: aland@physics.carleton.ca 

Colin McKay: Mail: c/o Northern Xposure 

Internet: crnckay@northx.isis.org 
Fidonet: Colin McKay @ 1:163/306 

Please include as much detail as is necessary to duplicate the 
problem, including module CRCs and hardware type if appropriate. 

5.7.2 Order Assistance 

For any problems with orders, defective disks or the manual, 
please contact your distributor at: 



World: Northern Xposure 
7 Greenboro Cres 
Ottawa, ON 
Canada 
KIT 1W6 

(613)736-0329 
Tuesday, 8-llpm EST 
is the best time. 



Australia: REMCOMS 

100 Whitsunday Dr 
KIRWAN. Qld. 
4817 
Australia 

+61 77 734884 



Internet : cmckay@nor thx . isis . org 
Fidonet : Colin McKay @ 1:163/306 
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